General Infomation PowerReplace converts text files using filter.   To realize the conversion, you need to write your own filter. There is some filter “ready to use” in the Filter folder. Please see the index in the Filter folder. You may also get more filter from my home page. Creating a New Filter In this tutorial, we will create a simple filter. By using it, PowerReplace will swap the two strings "read" and "write" in text file. For complete reference about filter, please see Chapter 5: Filter Syntax Reference. (1) Launch PowerReplace application. (2) Write the following lines in the window “Untitled”: % Comments: this filter swaps "read" and "write" % make sur there is no "re@d" in your text file. "read" "re@d" % save "read" to "re@d" "write" "read" % change "write" to "read" "re@d" "write" % change "re@d" to "write" ◊ If you have a very long line to edit, the line editor can help you. Please see the section Using Line Editor to Edit Long Line later in this Chapter. ◊ It is possible that there is some initial text in the window "Untitled". It contains help message for the beginners. The initial text in the three windows are stocked in the "Plugin:Initial Text For…" folder. You can change them or delete them if you wish. ◊ To open and edit an existed filter, or import an existed text file as filter, select Open Filter… (or press ⌘O) from the File menu. ◊ You can set some option for the editor, please see the section Text Option later in this Chapter. Converting a Text File In the “Untitled” window, click the Convert File button, then locate and select MyText to be converted from the standard get file dialog box. That’s all. Normally a new file named “MyText.out” has been created in the same folder as the file “MyText”.   ◊ You can use Balloon Help system to get description for buttons and menu items. Select Show Balloons from the help menu. ◊ It is possible that the filter has some errors. To debug filter, see Debugging Filter: Syntax Error and Logical Error later in this chapter. For complete reference about filter, please see Chapter 5: Filter Syntax Reference. ◊ You can set some options. For example, you may want to set the output file’s name by adding “.new” to the input file’s name, that is “MyText.new”. For complete description about how to set option, please see Filter Information later in this chapter. Converting the Clipboard To realize the conversion in a text editor (like BBEdit, Word), without saving the text as text file (of type 'TEXT'), follow these steps: (1) Under the text editor, select all your text by ⌘A, copy the selection by ⌘C. Now your text is in the clipboard. (2) Under PowerReplace, in the “Untitled” window, click the Convert Clipboard button. (3) Return to the text editor, paste the clipboard to your text by ⌘V. Converting Text Files Using Drag/Drop To realize frequently this conversion using drag/drop, follow these steps: (1) Save your filter. From the File menu, select Save or Save As… Then give this filter file a name, for example, “SimpleFilter” in the put file dialog box. Put it into the Filter folder. (2) Quit and relaunch PowerReplace application for some update information. (3) After confirming that there is an item SimpleFilter in the Filter menu, select it. Then quit. PowerReplace saves the selected filter SimpleFilter in its preference file.   (4) Under Finder, select your text files, drag and drop them onto the PowerReplace icon. That’s all. Normally the new files named “xxxxx.out” have been created in the same folder as the files “xxxxx”. ◊ To realize the same conversion that you have done the last time, you need only drag/drop your files onto the PowerReplace’s icon under Finder, because the selected filter is rememberred in the preference. ◊ Shortcuts. To select a filter and avoid opening it: ⌘ + Select Filter. ◊ The name of the selected filter appears in the toolbar. Converting All Text Files in a Folder Using Drag/Drop If you drop folder onto the application icon, PowerReplace converts all files in this folder and in the sub-folders of this folder by recurrence. Converting Text Files Using SelfReplace Please see Chapter 6: About SelfReplace. Converting Text Files Using Script If you have AppleScript system, you can write a small script for your conversion. Using the scripts, you have the following advantages: - Script is a very small file. - The filter need not be in the Filter folder. - Text file can be converted by filter1, then filter2. (Pipe) The following is the PowerReplace apple events’s dictionary: use filter: set new filter file use filter string -- name of the filter file to be used. current filter: get the name of the current filter file current filter Result: string -- name of the current filter file. convert: convert text file convert alias -- the input text files. using alias -- the filter file to be used. [message boolean] -- show the success message after conversion? Result: alias -- the output files. convert clipboard: convert clipboard convert clipboard using alias -- the filter file to be used. [message boolean] -- show the success message after conversion? The following is an example: on open doc set myfilter to choose file with prompt "Where is the filter?" tell application "PowerReplace 6.1 68K" launch activate set output to convert doc using myfilter with message quit end tell end open You can find more examples in the Example Script folder. Filter Information In the filter window, click Information, the filter information dialog box will display. You can set filter option in this dialog box. For complete description about each dialog item, please use Balloon Help system.   • Simple Output File Name. The formula for the output file name is: output file name = input name - deleteSuffix + addSuffix. For example, if input file name is "index.html", deleteSuffix is ".html", and addSuffix is ".tex". Then the output file name will be "index.tex". If the deleteSuffix can not be found, at the end of the input file name, then ignore the deleteSuffix. Change deleteSuffix and addSuffix in the "Information Window" of the filter. • Specify input file. You can specify input files. 4 cases: - all type, - all text file of type 'TEXT', - the name suffix is the string ".html", - the name suffix is NOT the string ".gif". You can change ".html" and ".gif" by other strings. Change this option in the "Information Window" of the filter. Debugging Filter: Syntax Error It is possible that the filter has some syntax errors. For complete reference about filter, please see Chapter 5: Filter Syntax Reference. Suppose that you write the following line "re@d" 3write" % change "re@d" to "write" in place of the last line of SimpleFilter. Click Convert File, Convert Clipboard or Check Syntax, the message window will display in the front. You can find enough help for correct the error.   Debugging Filter: Logical Error Of course, PowerReplace can not detect the logical errors. When the logical error occur, you need to do the following frequently: Edit filter -> Convert -> Check input and output In this case, you can put the input text in the “Input” window. Click Convert In->Out. PowerReplace does the convertion, and then displays the output text in the “Output” window. ◊ You can edit the text in the “Input” window, but can not edit the text in the “Output” window. ◊ The initial text in the three windows are stocked in the "Plugin:Initial Text For…" folder. It gives help for the beginners. You can change them or delete them if you wish. Text Option Select Text Option from the Edit menu. You can change text font and text size in the filter window. For the Automatical Alignment option, please see the following examples. If the filter text is %123456789ABCDEF0123456789ABCDEF0123456789ABCDEF "ab" "CD" "xy" "XY" "xyxyxyxyxyxyxyxyx" "XY" Then after check syntax, it will be: 1. without Automatical Alignment option. The text is not changed. 2. with Automatical Alignment option, Tabulation=16, Condense. %123456789ABCDEF0123456789ABCDEF0123456789ABCDEF "ab" "CD" "xy" "XY" "xyxyxyxyxyxyxyxyx" "XY" 3. with Automatical Alignment option, Tabulation=16, Extend. %123456789ABCDEF0123456789ABCDEF0123456789ABCDEF "ab" "CD" "xy" "XY" "xyxyxyxyxyxyxyxyx" "XY" Using Line Editor to Edit Long Line A good line in the filter window is like the following: first-stuff second-stuff the-rest If you have a long line in the filter window to edit, keep the cursor in that line and select "Line Editor" from the Edit menu. The Line Editor window displays. In this window, the first stuff, second stuff and the rest of that long line will be separated in three text fields. You can edit them more easily. ◊ We know that, in the first and second stuffs, \" represents ". In the line editor, we do NOT use this representation because there is no confusion. When back to the filter window by clicking the OK button, the line editor will replace " by \" automatically before making the long line. ◊ In the line editor, you can type CR or LF. When back to the filter window by clicking the OK button, the line editor will remove all CR and LF before making the long line. ◊ If the selected line is not a "good line", i.e., has no first stuff, or second stuff, then the line editor window does not display. Organizing the Filter Menu If there is too many filter files, the Filter menu will contain too many items. PowerReplace provides two ways to organize the Filter menu: ◊ you can mask someone of them by labelling (coloring) under Finder. PowerReplace scans only the folder and filter file without label(color). ◊ A filter named "(-" (without quotation marks) makes a divider line in the Filter menu. Stack Windows Use Stack Windows command in the Control menu to move all windows to its standard position.